Images and hubs topic

Resize and cache artwork, render UltraBlur backdrops, and read the hubs of the home screen, a section or an item.

Images

Resized artwork

final url = plex.images.transcodeUrl(
  sourcePath: item.thumb!, // e.g. '/library/metadata/123/thumb/1700000000'
  width: 300,
  height: 300,
);

final bytes = await plex.images.fetch(sourcePath: item.thumb!); // Uint8List?

Besides thumb and art, an item lists its artwork in images (PlexImage: type and url); squareArt is the 1:1 background (backgroundSquare) and logo the title logo (clearLogo), when the server has them. Any of these paths goes to transcodeUrl().

The server resizes the image (500 × 500 by default) and sends a JPEG. fetch() returns null on 404 and throws a PlexException on other failures, so "no artwork" and "try again later" stay apart. For blur, format and the other transcoder options see the transcoder URLs in Streaming.

Do not log these URLs. transcodeUrl(), ultraBlur.imageUrl() and collections.compositeImageUrl() answer URLs that carry the X-Plex-Token in their query, so an image widget can open them without headers. Before connect() they throw a state PlexException.

Artwork versions and cache keys

final cacheKey = '${album.ratingKey}@${album.thumbVersion}';
final version = PlexArtwork.versionOf('/library/metadata/123/thumb/1791659974');
// '1791659974'

An artwork path ends in a timestamp that changes whenever the image does. Put it in your cache key and a cover replaced on the server is fetched again. thumbVersion, artVersion, parentThumbVersion and grandparentThumbVersion read it off a PlexMetadata; a track without art of its own carries its album's thumb and version.

UltraBlur backdrops

The server extracts four corner colours from an image and renders them as a smooth gradient, for a backdrop behind a player screen:

final palettes = await plex.ultraBlur.colors(sourceUrl: album.thumb!);
final palette = palettes.first;

final url = plex.ultraBlur.imageUrl(
  topLeft: palette.topLeft,
  topRight: palette.topRight,
  bottomLeft: palette.bottomLeft,
  bottomRight: palette.bottomRight,
  width: 1920,
  height: 1080,
  noise: 1,
);
final png = await plex.ultraBlur.fetchImage(
  topLeft: palette.topLeft,
  topRight: palette.topRight,
  bottomLeft: palette.bottomLeft,
  bottomRight: palette.bottomRight,
  width: 1280,
  height: 720,
);

sourceUrl takes a library path or an absolute URL. The item details may already carry the palette, as PlexMetadata.ultraBlurColors. noise: 1 adds dither against banding, for a backdrop behind text. fetchImage() returns the PNG bytes, to cache yourself.

Hubs

Hubs are the rows of Plex's home screen: Recently Added, Continue Listening, More from an artist. Each PlexHub is a titled row of items.

Home and section hubs

final home = await plex.hubs.global(count: 8);
final musicHubs = await plex.hubs.forSection(sectionId: musicLib.id);

for (final hub in musicHubs) {
  print('${hub.title}: ${hub.items.length} items, more: ${hub.more}');
}

Each hub carries up to count items (16 by default) and more when it has others behind a "Show all". onlyTransient: true keeps the hubs that change with playback and additions.

final promoted = await plex.hubs.promoted();
final onDeck = await plex.hubs.continueWatching();
final musicOnDeck = await plex.hubs.sectionOnDeck(sectionId: musicLib.id);

continueWatching() and sectionOnDeck() return a List<PlexMetadata>, not hubs.

Drilling into a hub

final all = await plex.hubs.drill(
  hubKeyOrIdentifier: hub.hubKey, // or hub.hubIdentifier
  size: 100,
);

drill() pages the whole content of a hub with more. itemsByIdentifier(identifier:) does the same from an identifier such as library.recentlyAdded.3.

Hubs of an item

final aroundAlbum = await plex.hubs.forMetadata(metadataId: album.ratingKey);
final related = await plex.hubs.related(metadataId: album.ratingKey);
final afterPlay = await plex.hubs.postplay(metadataId: track.ratingKey);

forMetadata() returns the discovery rows of an item, such as "More by this artist", for music. related() returns related rows and postplay() the suggestions to show when an item ends.

Managing a section's hubs

With an admin token, manage(sectionId:) lists a section's hubs with their promotion flags. createCustom(), updateVisibility(), deleteCustom() and move() change them, and resetSection() restores the defaults:

final configured = await plex.hubs.manage(sectionId: musicLib.id);
await plex.hubs.updateVisibility(
  sectionId: musicLib.id,
  identifier: configured.first.hubIdentifier,
  promotedToOwnHome: true,
);

Classes

PlexArtwork Images and hubs
Helpers for PMS artwork paths.
PlexHub Images and hubs
One <Hub> entry from /hubs or /hubs/search — a titled, optionally paginated bucket of PlexMetadata items grouped by Plex.
PlexHubsApi Images and hubs
/hubs/* — global and per-section discovery rails.
PlexImage Images and hubs
One entry of PlexMetadata.images.
PlexImagesApi Images and hubs
Build & fetch artwork URLs through the server's image transcoder (/photo/:/transcode).
PlexUltraBlurApi Images and hubs
/services/ultrablur/* — server-side palette extraction and gradient backdrop rendering.
PlexUltraBlurColors Images and hubs
Four hex colours extracted from an image by the Plex server. Use the same four values to ask /services/ultrablur/image for a server-rendered gradient backdrop.